TO WORD WRAP THIS TEXT:

Click Edit on this screen's above toolbar and then click on Word Wrap.

TK3 SIMULATION NOTES 14DEC04

GENERAL

This mini simulator does not attempt to match the facilities of more sophisticated commercial simulators. It basically shows the behaviour of the commands in a program and the affects that they have upon the registers accessed. The following are not supported:

ALL FAMILIES

* Interrupts
* Access to Data Eeprom
* PortB pullups
* Sleep
* Analogue inputs and other special I/O functions (e.g. RS232)
Timers, including WatchDog, with the exception that a mock creation of a TMR0 rollover is generated in response to the simulator's own internal timer

PIC18F ONLY

* PCLATH
* INDF
* FSR
* OPTION_REG
* TBLRD, TBLWT
* INTCON (but note that testing INTCON1,2 for being set, sets that bit to simplify simulation routines that use timing involving INTCON1 to determine pause lengths before doing the next task)
* ADCON0 (but note that testing ADCON0,GO for being clear, clears that bit to simplify simulation routines that use ADC reading before doing the next task)

For non-PIC18F devices the simulator has a limit of 8000 commands and 512 registers (4 Banks, 0 to 3).

For PIC18F devices it has a limit of 8000 commands and 4096 registers (16 Banks, 0 to 15).

All code changes must be made through the normal Edit/Assemble functions, they cannot be changed from within the simulator.

USING THE SIMULATOR

Hover the mouse over various on-screen functions for info on what they do.

If you cannot see a full command line in the List box, clicking the mouse on it places it in a ToolTipText box which will be shown a second or so later.
 
To run the simulator, the source code (ASM) file must first be assembled in the usual way. An additional file having the same name, but suffixed SIM, is created. This file is the one used by the simulator. It contains the command lines extracted from the ASM file, the hexadecimal values created during the assembly process (as also compiled into the normal HEX file), and line count values, which are the addresses within the PIC to which the values are downloaded during programming. Where commands have been substituted through such functions as DEFINE, the command line is prefixed by a hash (#) symbol and then shows the original Define command, followed by its defined meaning (e.g. # BANK0 BSF 3,5 - where BANK0 has been defined as BSF 3,5).

When assembling an ASM file, unless it has the PIC type embedded in it (near the top of its code, in the form: LIST = P16F84, R = DEC) you MUST set the PIC type correctly via the usual option.

Two buttons are provided for running the simulator. The Run Sim button sets the simulator into automatic run mode, stepping through the commands at a rate determined by the sim program's internal timer interrupt. When clicked to start running, its caption changes to Stop Sim and its green colour changes to red. Click the button to stop automatic running. The Step Sim button when clicked steps the simulator to the next command and actions it, then waits for the next click.

The results of the commands that change registers are displayed appropriately in the register boxes on the main screen area. They are arranged in columns in numerical order. Commands which affect the W register and the C, DC and Z (plus IRP, RP1 and RP0 - non-18F) (plus N and OV for 18F), flags have their results displayed in separate boxes below the command list.

For non-18F devices, the screen holds the register boxes for one PIC Bank (128 registers). The Bank displayed may be changed via the Bank "radio" buttons at the top of the screen.

For 18F devices, the screen holds the register boxes for half a PIC Bank (128 registers). The Bank displayed may be changed via the Bank "tick" boxes at the top of the screen. The boxes are in pairs (A/B), the left-hand box indicates the lower half of the Bank (0 to 127), the right-hand box indicates the upper half of the Bank (128 to 255). The upper half of Bank 15 holds the SFRs (Special Function Registers). The Bank groups of the first three pairs of tick boxes (as indicated by their captions) can be changed by the INC button, which adds three to the value of the current Bank group, rolling back to group 0 to 2 after the fifth group (12 to 14).

Register values may be displayed in decimal, hex or binary, as selected by the Radix buttons.

Hovering the mouse over a register value causes it to be displayed in decimal, hex and binary, within a ToolTipText box.

Register values when shown can be amended when the simulator is in Step mode. Click on the value you wish to change, change it via the bit boxes or the text box revealed. When changes have been completed press Enter or click on the filename box above the buttons to activate them. Clicking Run Sim or Step Sim also activates them. Text box values must be in decimal. 

PORTS

The Ports are different to other registers in a PIC in that they are effectively two registers, one for data output to the world, the other for input from it, as determined by the setting of their TRIS (data direction) registers.

The basic function of a Port bit is illustrated in the schematic drawing shown when the Ports Info button is clicked. Microchip state that:

"Reading a port register reads the status of the pin, whereas writing to it will write to the port latch. All write operations are read-modify-write operations, so a write to a port implies that the port pins are first read, then this value is modified and written to the port data latch."

At the bottom of the screen, the PORT IN buttons in the first line represent the data logic levels available to be input when the relevant TRIS bit is set for input, alternating between High and Low logic when clicked, black or white respectively. The blue boxes below them show the equivalent numerical value of the input logic bits.

The small PORT OUT boxes represent the logic levels available to be output to the world from the data latch. The value is that determined by reads from the input pins and that set by data writes to a port (re-read Microchip's statement if this is not immediately clear). The data actually output is modifified by whether relevant TRIS pins are set for input or output. The blue PORT OUT boxes show the equivalent numerical value of the data latch contents. On the main body of the screen, the register boxes for the Ports show the same data latch value.

The bottom line of boxes shows the TRIS bits, red for input mode, and blue for output mode.

Some PICs have other, non-digital, modes into which Port pins can be set, such as via CMCON (PIC16F62x) for instance. A bottom line of boxes indicates which pins are selected for non-digital mode.

"MISSING" LABELS

Labels written into an ASM file are only repeated in the SIM file if they have a command associated with them. The SIM file is created at the same time as the HEX file and records only those statements for which a code value and address are given. Any line without such is ignored. The SIM screen list box is arranged in strict numerical order of addresses as the PIC would see them and any additinal lines would throw the program count correctness and Calls/Gotos/Returns etc would not be implemented properly. The only way round this is for you to add NOP at any label without a command where the label needs to be shown in the SIM list.

STACK

PICs have a Stack register which keeps track of return addresses when CALL commands are actioned. In a non-18F PIC this register cannot be read or written to directly. It has a limit of 8 values for non-18F PICs and 31 for 18F PICs, and can be inadvertently overwritten if this value is exceeded in a complex program with nested sub-calls. This simulator keeps track of the Stack status and displays it in a separate list box. The values shown are the addresses, in reverse calling order (last in, first out) and in decimal, to which the program jumps when a RETURN command issued. The values are one-greater than the address from which the CALL was made.

FIND

A Find facility allows the command list to be searched for any word (or phrase or value) which is keyed in to the text box below the command list. Having typed it, click the Find button, or press Enter, an action which may be repeated to find the next occurrence of the word.

Having searched the full command list, the process returns to the first command in the list and stops there until reactivated.

COMMAND TIMINGS

Each command actioned takes one or two PIC cycles (as listed in its data sheet), which occur at one quarter of the PIC's clock (e.g. crystal) rate. The simulator keeps track of the command cycles and displays them at the bottom left of the screen. By default they are in relation to a 4MHz crystal rate (1 cycle = 1 microsecond). You may change this rate via the Combo box below the cycle counter display. The choices are 32768Hz, 3.2768MHz, 4MHz, 10MHz, 20MHz. No provision has been made to add to the choices. Click on the box's arrow and select from the list displayed. The choice is not stored for future recall when next the program is run, reverting to 4MHz.

BREAKPOINTS

The boxes in the command list may be left-clicked to select breakpoints at which the program halts when run in automatic mode. When first clicked, a tick mark appears which indicates an active breakpoint. Clicking again turns the function off. It is an alternating cycle. All breakpoints may be cleared by clicking on the Clear Breaks button at the screen's top right. It is important to note that it is the BOX which must be click, not the line itself. The latter MAY appear to work sometimes, but the tick behaviour can be erratic. Do not double-click a box.

Left-clicking followed by right-clicking the mouse also causes the current blue-highlighted command line number to be set as line number from which the program starts its simulation. This number is stated below the list. Clicking the RPT (Repeat) button resets the list's start position to the same line at which a click was last made. The default is line zero when the program is first entered.

HIDE UNUSED

Normally, the screen displays all registers associated with a 128-register Bank group. You may "hide" unused registers by clicking on the Hide Unused tick box at the bottom left. Re-click to redisplay them all.

CLEAR REGISTERS

Having run a simulation to a particular point, you may reset (null) all the resister values generated in that process by clicking the Reset button. This automatically returns the command list count to the first command.

EDIT AND ASSEMBLY BUTTONS

The Edit button calls up the same Edit facility as accessed via TK3's main screen, allowing the ASM code to be modified. Exiting the Edit function returns you to the Sim screen, where an Assembly button is now shown. Click it to start code assembly in the normal way. On completion of the assembly, that sub-screen offers the same options as usual, plus the option to re-enter the Simul screen. (It has proved impossible to offer an automatic assembly entry from the Simul screen following exit from Edit - as is provided via the main screen's function, using the Enter key.)

The Edit and Assembly buttons are hidden during automatic simulation mode.

TRACE BUTTON

The Trace tick box allows you to make a record of the commands actioned while in automatic run mode. On starting the run, a file is opened (TK3Trace.txt) and each command actioned has its code line output to the text file, along with its address value. On stopping auto-run, the file is closed and can then be examined via the Show Trace button.

The recording always takes place from the current line selected. The recording facility is not available when single-stepping a program, or when the Trace box is unticked. The record is always overwritten when a new run is started.

MAIN SCREEN SIMUL BUTTON

The Simulation facility can be inhibited via the main screen. To the left of the Simulation button is tick box. Click the box to hide the tick, this also hides the Simulation button. Reclick to tick box to reactivate the option.

The benefit of turning off the Simul option is that it prevents .SIM files being created during the assembly process. If you are changing the ASM file name for each new version of that code (as is recommended, by using a suffix number for example), your disk drive could become "well-populated" by SIM files that you do not need. This inhibit option prevents SIM files from being created when you do not want them.

SIM FILE EXAMINATION

The Sim file may be examined via the main screen or sim screen View Sim buttons. This is for information only and has no practical purpose.

SIMULATING HEX FILES

If you only have a HEX file for a particular program and wish to simulate it, first convert the HEX file to an ASM file via TK3's disassembly option. Then use the resulting ASM file for the simulation (re-assembling it first in order to created the required SIM file). Remember that you must set the PIC Type for the PIC being disassembled.

John Becker


